Repository navigation
Version Packages - #3106
Version Packages#3106github-actions[bot] wants to merge 1 commit into
Conversation
2a9a2bb to
338a7d4
Compare
338a7d4 to
3b9a2d9
Compare
3b9a2d9 to
abbed23
Compare
|
|
||
| - [#3108](https://github.com/modelcontextprotocol/typescript-sdk/pull/3108) [`39ae8e6`](https://github.com/modelcontextprotocol/typescript-sdk/commit/39ae8e6192cf43273aaaf2de4169dfa9f7216e28) Thanks [@claude](https://github.com/apps/claude)! - The bundled Ajv validator is now built with fast-uri 3.1.9 (was 3.1.8). A schema no longer compiles when a `$id` or `$ref` has a percent-encoded character before its first colon (`%61:b`), or `{` or `}` in the host of an `http`, `https`, `ws` or `wss` URL (`http://{host}/a`). Relative values keep their leading `..` segments: a `$ref` to a `$id` such as `../a` now resolves, and a `$ref` of only dot segments (`.`, `../`) no longer resolves to the root schema. Plain names, `#/$defs/...` references, other URLs and URNs are not affected. | ||
|
|
||
| - [#3167](https://github.com/modelcontextprotocol/typescript-sdk/pull/3167) [`919bb8e`](https://github.com/modelcontextprotocol/typescript-sdk/commit/919bb8ea88b6e10e72c2f8b6218fad4cfdc40b2c) Thanks [@mattzcarey](https://github.com/mattzcarey)! - Reject a `tools/call` with `400` / `-32020` (`HeaderMismatch`) when a body argument declared with `x-mcp-header` is an object or array, with or without its `Mcp-Param-*` header, and when the argument is an integer outside the safe range but the header is present. Previously the header check was skipped for these values, so the call reached the tool. |
There was a problem hiding this comment.
🟡 nit (optional): The 2.5.0 changelog tells readers that object or array arguments used to reach the tool, which normally they did not. Before #3167 the skipped header check fell through to validateToolInput (packages/server/src/server/mcp.ts:306). A schema that enforces the declared primitive type then answered 200 with isError: true and the handler never ran. Fix: reword the "Previously ..." sentence to say the call went on to argument validation and reached the handler only when that validation accepted the value, as for an unsafe integer; same text at packages/core-internal/CHANGELOG.md:20.
Why this was flagged
The trigger is a tools/call through createMcpHandler whose x-mcp-header-declared argument is an object or array. packages/server/CHANGELOG.md:22 and packages/core-internal/CHANGELOG.md:20 say "Previously the header check was skipped for these values, so the call reached the tool." On the commit before 919bb8e the check did continue, the request was dispatched, and packages/server/src/server/mcp.ts:306 ran validateToolInput before executeToolHandler at mcp.ts:307. A validator that enforces type: 'string' fails there, and mcp.ts:316-320 turns that into a 200 result with isError: true and "Input validation error"; the handler is not called. A reader gets a wrong account of the old behaviour and is not told the visible change for the common case: a 200 tool-error result becomes a 400 / -32020 protocol error. No safeguard applies: the changelog text is copied verbatim from the deleted .changeset/mcp-param-header-non-primitive-body.md.
Verification: packages/server/CHANGELOG.md:22 and packages/core-internal/CHANGELOG.md:20, both added by this diff, say: "Previously the header check was skipped for these values, so the call reached the tool." The catch at mcp.ts:316-320 turns the throw into createToolError(...), an isError: true result, and executeToolHandler at mcp.ts:307 is never reached.
Finding ID: f-68b7a9d1
abbed23 to
c715b93
Compare
| Code that compiled before can now fail to compile, for a tool with an `outputSchema`, when the callback: | ||
| - returns `structuredContent` that does not match the schema, or a successful result without it; | ||
| - builds the value from a wider type than the schema (e.g. `string` for an enum); | ||
| - has its result typed as plain `CallToolResult` (a `Promise<CallToolResult>` annotation, a helper returning `CallToolResult`, or `ToolCallback<typeof inputSchema>`); use `ToolCallback<typeof inputSchema, typeof outputSchema>` or drop the annotation; | ||
| - is registered with an `outputSchema` typed `S | undefined`, which is checked as if present. |
There was a problem hiding this comment.
🟡 nit (optional): Users upgrading to 2.5.0 can hit compile errors the changelog's break list does not name, in code that passed runtime output validation. The list at packages/server/CHANGELOG.md:23 says only "does not match the schema". ToolStructuredContent (mcp.ts:1367) also rejects an omitted .default() field, a coerced input such as '1', an unbranded value and a type-changing transform. An error result whose isError is typed boolean fails too. Fix: name these cases in the break list, with ToolErrorResult as the return type for error helpers.
Why this was flagged
Trigger: a tool with outputSchema: z.object({ n: z.number().default(0) }) returning structuredContent: {}, z.coerce.number() returning '1', a .brand<'Id'>() field given a plain string, or an error helper whose inferred return type is { content; isError: boolean }, passed to McpServer.registerTool. packages/server/src/server/mcp.ts:1370-1372 types the value as the schema output, or input & output; packages/server/test/server/registerToolOutputTyping.test.ts:96, :101 and :263 pin the first three as @ ts-expect-error. mcp.ts:1390 (isError?: false) and mcp.ts:1394 (isError: true) leave no union member for boolean without structuredContent. On the base the callback returned CallToolResult, so all four compiled, and at runtime mcp.ts:411 validateStandardSchema accepts the values. CHANGELOG.md:23-26 list four cases, none of these. No safeguard: the text is copied from the deleted .changeset/register-tool-output-typing.md.
Verification: packages/server/src/server/mcp.ts:1370-1372 types the value as InferOutput, or InferInput & InferOutput when output is not a valid input. Runtime side: mcp.ts:411 runs validateStandardSchema(tool.outputSchema, result.structuredContent) and the raw value is sent on, so {} and '1' pass. The default, coercion, transform and widened-isError cases are not named.
Finding ID: f-bf331e78
c715b93 to
23a0833
Compare
23a0833 to
c9395e2
Compare
c9395e2 to
c463b45
Compare
This PR was opened by the Changesets release GitHub action. When you're ready to do a release, you can merge this and publish to npm yourself or setup this action to publish automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to main, this PR will be updated.
Releases
@modelcontextprotocol/client@2.5.0
Minor Changes
#2370
2ada652Thanks @mattzcarey! - Add aloggeroption toClient,McpServer,createMcpHandlerand the built-in OAuth providers such asClientCredentialsProvider, and an optionalsdkLoggerproperty toOAuthClientProvider, so SDK diagnostics can be routed through user-provided logging. Omitting them keeps the currentconsoleoutput.#3115
1e608caThanks @mattzcarey! -Client,ServerandMcpServernow emit OpenTelemetry spans andmcp.client.operation.duration/mcp.server.operation.durationhistograms for every MCP request and notification exceptnotifications/message, following the OpenTelemetry semantic conventions for MCP, and propagate W3C trace context throughparams._meta(SEP-414). There is nothing to configure: register an OpenTelemetry SDK and MCP traffic shows up. PassopenTelemetry: falseto aClient,ServerorMcpServerto turn its instrumentation off. Without one, the OpenTelemetry API is a no-op, nothing is recorded and messages are unchanged.@opentelemetry/api(^1.9.0) is a new required peer dependency of@modelcontextprotocol/clientand@modelcontextprotocol/server, so the SDK uses the same copy as the application's OpenTelemetry SDK. npm 7+, pnpm 8+ and Bun install it automatically. Setups that don't install peers must add@opentelemetry/apito their dependencies, or importing either package fails: Yarn (classic, and Berry with any linker),npm --legacy-peer-deps, and pnpm withauto-install-peers=false.What changes for applications that already run an OpenTelemetry SDK:
@modelcontextprotocol/clientand@modelcontextprotocol/serverinstrumentation scopes. If you already trace MCP, passopenTelemetry: false, or with Sentry remove itsMcpServerintegration, to avoid duplicate spans. Filtering the MCP scopes instead leaves handler spans parented on spans that are never exported.params._meta, as HTTP requests carry it in headers:traceparentandtracestate, plusbaggageif the propagator includes W3C Baggage (theNodeSDKdefault), so baggage entries reach MCP peers, including third-party servers. RegisterW3CTraceContextPropagatoralone to send trace context only._metamember, as they already do for callers that passonprogress.Spans do not record tool arguments, tool results or prompt arguments. They do record JSON-RPC error messages, handler exception messages and resource URIs. The span and attribute names are experimental while the MCP semantic conventions are in development.
#2820
600f69dThanks @mattzcarey! - Server and client extensions (experimental: theextensionsoption, the extension shapes and their contexts,useandacceptResultTypemay change in a minor release while the extensions SEPs settle). An extension is{ id, setup(ctx) }, passed inMcpServerOptions.extensionsorClientOptions.extensions.setupruns at construction, in array order, and adds everything through its context. It may be async: the setups after it wait for it, andconnectwaits for all of them and rejects if one fails. Its context provides:ctx.capability(settings)sets what is advertised undercapabilities.extensions[id]({}by default),ctx.setRequestHandler(name, schemas, handler)registers the handler for a custom request method and refuses core request and notification names and methods that already have a handler,ctx.use(method, middleware)wraps a method's handler, andctx.require(extensionId)declares that the extension needs another extension, failing construction when it isn't installed (orconnect, from or after an asyncsetup). The server context also carriesctx.mcp, theMcpServer; the client context carriesctx.clientandctx.acceptResultType. A duplicate id, or an entry for an installed id incapabilities.extensions, fails construction before any extension is set up;registerCapabilitiesalso refuses an installed id's entry.Protocol.use(method, (request, ctx, next) => …)is middleware around the registered handler, composed at dispatch time in registration order, inside middleware extensions add withctx.use, so middleware ontools/callapplies even thoughMcpServerregisters that handler lazily; it returns a remover. Middleware sees the request before params validation and therequestState.verifyhook. On a method with no handler,nextthrowsMethodNotFound, which a per-request HTTP exchange answers with 404 when the middleware passes it through.Protocol.acceptResultType(method, resultType)declares an extension result kind for a method: a raw response carrying thatresultTypebypasses the era codec's closed vocabulary and is validated against the caller's explicit result schema as-is, while typed calls such ascallToolreject it withUnsupportedResultTypeon either protocol version; that is how a client extension receives shapes such as the Tasks extension'sresultType: "task"ontools/call.useandctx.usewrap requests this side receives: a core notification,subscriptions/listenon a server, or a core request this side is never sent throws aTypeError.Patch Changes
#3108
39ae8e6Thanks @claude! - The bundled Ajv validator is now built with fast-uri 3.1.9 (was 3.1.8). A schema no longer compiles when a$idor$refhas a percent-encoded character before its first colon (%61:b), or{or}in the host of anhttp,https,wsorwssURL (http://{host}/a). Relative values keep their leading..segments: a$refto a$idsuch as../anow resolves, and a$refof only dot segments (.,../) no longer resolves to the root schema. Plain names,#/$defs/...references, other URLs and URNs are not affected.#2877
b415e60Thanks @dasjideepak! - AddOAuthClientProvider.skipOfflineAccessConsentPrompt(and the matchingstartAuthorization()option) so a client can omit theprompt=consentthe SDK adds when the requested scope includesoffline_access. Default behavior is unchanged. This unblocks authorization servers such as Microsoft Entra ID tenants that have user consent disabled and admin consent granted, where a forced consent prompt fails withAADSTS90095for non-admin users.Updated dependencies []:
@modelcontextprotocol/server@2.5.0
Minor Changes
#2370
2ada652Thanks @mattzcarey! - Add aloggeroption toClient,McpServer,createMcpHandlerand the built-in OAuth providers such asClientCredentialsProvider, and an optionalsdkLoggerproperty toOAuthClientProvider, so SDK diagnostics can be routed through user-provided logging. Omitting them keeps the currentconsoleoutput.#3115
1e608caThanks @mattzcarey! -Client,ServerandMcpServernow emit OpenTelemetry spans andmcp.client.operation.duration/mcp.server.operation.durationhistograms for every MCP request and notification exceptnotifications/message, following the OpenTelemetry semantic conventions for MCP, and propagate W3C trace context throughparams._meta(SEP-414). There is nothing to configure: register an OpenTelemetry SDK and MCP traffic shows up. PassopenTelemetry: falseto aClient,ServerorMcpServerto turn its instrumentation off. Without one, the OpenTelemetry API is a no-op, nothing is recorded and messages are unchanged.@opentelemetry/api(^1.9.0) is a new required peer dependency of@modelcontextprotocol/clientand@modelcontextprotocol/server, so the SDK uses the same copy as the application's OpenTelemetry SDK. npm 7+, pnpm 8+ and Bun install it automatically. Setups that don't install peers must add@opentelemetry/apito their dependencies, or importing either package fails: Yarn (classic, and Berry with any linker),npm --legacy-peer-deps, and pnpm withauto-install-peers=false.What changes for applications that already run an OpenTelemetry SDK:
@modelcontextprotocol/clientand@modelcontextprotocol/serverinstrumentation scopes. If you already trace MCP, passopenTelemetry: false, or with Sentry remove itsMcpServerintegration, to avoid duplicate spans. Filtering the MCP scopes instead leaves handler spans parented on spans that are never exported.params._meta, as HTTP requests carry it in headers:traceparentandtracestate, plusbaggageif the propagator includes W3C Baggage (theNodeSDKdefault), so baggage entries reach MCP peers, including third-party servers. RegisterW3CTraceContextPropagatoralone to send trace context only._metamember, as they already do for callers that passonprogress.Spans do not record tool arguments, tool results or prompt arguments. They do record JSON-RPC error messages, handler exception messages and resource URIs. The span and attribute names are experimental while the MCP semantic conventions are in development.
#2449
350f916Thanks @mattzcarey! -McpServer.registerToolnow type-checks a callback's successful result against the tool'soutputSchema, for Standard Schema and deprecated raw-shape schemas. A successful result must includestructuredContentthat matches the schema and is notundefined;isError: trueresults, input-required results, tools without anoutputSchema, and tools whose schema has anunknownoutput type (such as an untypedfromJsonSchema(...)) are unchanged. Runtime output validation is unchanged.New exported types:
ToolResultFor,ToolStructuredContent,ToolResultWithStructuredContent,ToolErrorResult.ToolCallbacktakes an optional second type parameter for the output schema.Code that compiled before can now fail to compile, for a tool with a typed
outputSchema, when the callback:structuredContentthat does not match the schema, or a successful result without it;stringfor an enum);CallToolResult(aPromise<CallToolResult>annotation, a helper returningCallToolResult, orToolCallback<typeof inputSchema>); useToolCallback<typeof inputSchema, typeof outputSchema>or drop the annotation;outputSchemathat may beundefined, which is checked as if present.#2820
600f69dThanks @mattzcarey! - Server and client extensions (experimental: theextensionsoption, the extension shapes and their contexts,useandacceptResultTypemay change in a minor release while the extensions SEPs settle). An extension is{ id, setup(ctx) }, passed inMcpServerOptions.extensionsorClientOptions.extensions.setupruns at construction, in array order, and adds everything through its context. It may be async: the setups after it wait for it, andconnectwaits for all of them and rejects if one fails. Its context provides:ctx.capability(settings)sets what is advertised undercapabilities.extensions[id]({}by default),ctx.setRequestHandler(name, schemas, handler)registers the handler for a custom request method and refuses core request and notification names and methods that already have a handler,ctx.use(method, middleware)wraps a method's handler, andctx.require(extensionId)declares that the extension needs another extension, failing construction when it isn't installed (orconnect, from or after an asyncsetup). The server context also carriesctx.mcp, theMcpServer; the client context carriesctx.clientandctx.acceptResultType. A duplicate id, or an entry for an installed id incapabilities.extensions, fails construction before any extension is set up;registerCapabilitiesalso refuses an installed id's entry.Protocol.use(method, (request, ctx, next) => …)is middleware around the registered handler, composed at dispatch time in registration order, inside middleware extensions add withctx.use, so middleware ontools/callapplies even thoughMcpServerregisters that handler lazily; it returns a remover. Middleware sees the request before params validation and therequestState.verifyhook. On a method with no handler,nextthrowsMethodNotFound, which a per-request HTTP exchange answers with 404 when the middleware passes it through.Protocol.acceptResultType(method, resultType)declares an extension result kind for a method: a raw response carrying thatresultTypebypasses the era codec's closed vocabulary and is validated against the caller's explicit result schema as-is, while typed calls such ascallToolreject it withUnsupportedResultTypeon either protocol version; that is how a client extension receives shapes such as the Tasks extension'sresultType: "task"ontools/call.useandctx.usewrap requests this side receives: a core notification,subscriptions/listenon a server, or a core request this side is never sent throws aTypeError.#3153
5ee54eeThanks @mattzcarey! - AMcpServertool result withstructuredContentand nocontentnow gets a text block holding the serialized JSON ofstructuredContent, as the tools spec recommends, instead ofcontent: []. This applies to every tool result, with or without anoutputSchemaorisError. A result that suppliescontent, even an empty array, is handled as before. To match, successful results of a tool with a typedoutputSchemamay omitcontentin TypeScript, both inregisterTooland inRegisteredTool.update({ callback }).Patch Changes
#3108
39ae8e6Thanks @claude! - The bundled Ajv validator is now built with fast-uri 3.1.9 (was 3.1.8). A schema no longer compiles when a$idor$refhas a percent-encoded character before its first colon (%61:b), or{or}in the host of anhttp,https,wsorwssURL (http://{host}/a). Relative values keep their leading..segments: a$refto a$idsuch as../anow resolves, and a$refof only dot segments (.,../) no longer resolves to the root schema. Plain names,#/$defs/...references, other URLs and URNs are not affected.#3167
919bb8eThanks @mattzcarey! - Reject atools/callwith400/-32020(HeaderMismatch) when a body argument declared withx-mcp-headeris an object or array, with or without itsMcp-Param-*header, and when the argument is an integer outside the safe range but the header is present. Previously the header check was skipped for these values, so the call reached the tool.Updated dependencies []:
@modelcontextprotocol/server-legacy@2.5.0
Patch Changes
@modelcontextprotocol/codemod@2.5.0
@modelcontextprotocol/core@2.5.0
@modelcontextprotocol/core-internal@2.1.0
Minor Changes
#2370
2ada652Thanks @mattzcarey! - Add aloggeroption toClient,McpServer,createMcpHandlerand the built-in OAuth providers such asClientCredentialsProvider, and an optionalsdkLoggerproperty toOAuthClientProvider, so SDK diagnostics can be routed through user-provided logging. Omitting them keeps the currentconsoleoutput.#3115
1e608caThanks @mattzcarey! -Client,ServerandMcpServernow emit OpenTelemetry spans andmcp.client.operation.duration/mcp.server.operation.durationhistograms for every MCP request and notification exceptnotifications/message, following the OpenTelemetry semantic conventions for MCP, and propagate W3C trace context throughparams._meta(SEP-414). There is nothing to configure: register an OpenTelemetry SDK and MCP traffic shows up. PassopenTelemetry: falseto aClient,ServerorMcpServerto turn its instrumentation off. Without one, the OpenTelemetry API is a no-op, nothing is recorded and messages are unchanged.@opentelemetry/api(^1.9.0) is a new required peer dependency of@modelcontextprotocol/clientand@modelcontextprotocol/server, so the SDK uses the same copy as the application's OpenTelemetry SDK. npm 7+, pnpm 8+ and Bun install it automatically. Setups that don't install peers must add@opentelemetry/apito their dependencies, or importing either package fails: Yarn (classic, and Berry with any linker),npm --legacy-peer-deps, and pnpm withauto-install-peers=false.What changes for applications that already run an OpenTelemetry SDK:
@modelcontextprotocol/clientand@modelcontextprotocol/serverinstrumentation scopes. If you already trace MCP, passopenTelemetry: false, or with Sentry remove itsMcpServerintegration, to avoid duplicate spans. Filtering the MCP scopes instead leaves handler spans parented on spans that are never exported.params._meta, as HTTP requests carry it in headers:traceparentandtracestate, plusbaggageif the propagator includes W3C Baggage (theNodeSDKdefault), so baggage entries reach MCP peers, including third-party servers. RegisterW3CTraceContextPropagatoralone to send trace context only._metamember, as they already do for callers that passonprogress.Spans do not record tool arguments, tool results or prompt arguments. They do record JSON-RPC error messages, handler exception messages and resource URIs. The span and attribute names are experimental while the MCP semantic conventions are in development.
#2820
600f69dThanks @mattzcarey! - Server and client extensions (experimental: theextensionsoption, the extension shapes and their contexts,useandacceptResultTypemay change in a minor release while the extensions SEPs settle). An extension is{ id, setup(ctx) }, passed inMcpServerOptions.extensionsorClientOptions.extensions.setupruns at construction, in array order, and adds everything through its context. It may be async: the setups after it wait for it, andconnectwaits for all of them and rejects if one fails. Its context provides:ctx.capability(settings)sets what is advertised undercapabilities.extensions[id]({}by default),ctx.setRequestHandler(name, schemas, handler)registers the handler for a custom request method and refuses core request and notification names and methods that already have a handler,ctx.use(method, middleware)wraps a method's handler, andctx.require(extensionId)declares that the extension needs another extension, failing construction when it isn't installed (orconnect, from or after an asyncsetup). The server context also carriesctx.mcp, theMcpServer; the client context carriesctx.clientandctx.acceptResultType. A duplicate id, or an entry for an installed id incapabilities.extensions, fails construction before any extension is set up;registerCapabilitiesalso refuses an installed id's entry.Protocol.use(method, (request, ctx, next) => …)is middleware around the registered handler, composed at dispatch time in registration order, inside middleware extensions add withctx.use, so middleware ontools/callapplies even thoughMcpServerregisters that handler lazily; it returns a remover. Middleware sees the request before params validation and therequestState.verifyhook. On a method with no handler,nextthrowsMethodNotFound, which a per-request HTTP exchange answers with 404 when the middleware passes it through.Protocol.acceptResultType(method, resultType)declares an extension result kind for a method: a raw response carrying thatresultTypebypasses the era codec's closed vocabulary and is validated against the caller's explicit result schema as-is, while typed calls such ascallToolreject it withUnsupportedResultTypeon either protocol version; that is how a client extension receives shapes such as the Tasks extension'sresultType: "task"ontools/call.useandctx.usewrap requests this side receives: a core notification,subscriptions/listenon a server, or a core request this side is never sent throws aTypeError.Patch Changes
#3167
919bb8eThanks @mattzcarey! - Reject atools/callwith400/-32020(HeaderMismatch) when a body argument declared withx-mcp-headeris an object or array, with or without itsMcp-Param-*header, and when the argument is an integer outside the safe range but the header is present. Previously the header check was skipped for these values, so the call reached the tool.Updated dependencies []: